<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta name="copyright" content=
"Copyright (c) IBM Corporation and others 2000, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css" />
<title>Presenting Java elements in a JFace viewer</title>

</head>
<body>
<h2>Presenting Java Elements in a JFace Viewer</h2>
<p>The JDT UI API provides classes that allow you to present the Java model or parts of it in a
standard JFace viewer. This functionality is provided primarily by:</p>

<ul>
<li><a href=
"../reference/api/org/eclipse/jdt/ui/StandardJavaElementContentProvider.html"><b>StandardJavaElementContentProvider</b></a>
- translates the Java element hierarchy into a data structure accessible by a tree, table or list
viewer</li>
<li><a href=
"../reference/api/org/eclipse/jdt/ui/JavaElementLabelProvider.html"><b>JavaElementLabelProvider</b></a>
- provides corresponding images and labels for a standard JFace viewer</li>
<li><a href=
"../reference/api/org/eclipse/jdt/ui/JavaElementLabels.html"><b>JavaElementLabels</b></a> -
provides corresponding text labels for Java elements</li>
</ul>
<p>Content and label providers for JFace viewers are described in detail in <a href=
"../../org.eclipse.platform.doc.isv/guide/jface_viewers.htm" class="XRef">JFace viewers</a>.</p>

If you understand the basic platform mechanism, then putting the Java content and label providers
together is quite simple:
<pre class="color1">
    ...
    TreeViewer viewer= new TreeViewer(parent);
    // Provide members of a compilation unit or class file
    ITreeContentProvider contentProvider= new StandardJavaElementContentProvider(true);
    viewer.setContentProvider(contentProvider);
    // There are more flags defined in class JavaElementLabelProvider
    ILabelProvider labelProvider= new JavaElementLabelProvider(
        JavaElementLabelProvider.SHOW_DEFAULT |
        JavaElementLabelProvider.SHOW_QUALIFIED |
        JavaElementLabelProvider.SHOW_ROOT);
    viewer.setLabelProvider(labelProvider);
    // Using the Java model as the viewers input present Java projects on the first level.
    viewer.setInput(JavaCore.create(ResourcesPlugin.getWorkspace().getRoot()));
    ...
</pre>
<p>The example above uses a Java model (<a href=
"../reference/api/org/eclipse/jdt/core/IJavaModel.html"><b>IJavaModel</b></a>) as the input element
for the viewer.&nbsp; The <a href=
"../reference/api/org/eclipse/jdt/ui/StandardJavaElementContentProvider.html"><b>StandardJavaElementContentProvider</b></a>
also supports <a href=
"../reference/api/org/eclipse/jdt/core/IJavaProject.html"><b>IJavaProject</b></a>, <a href=
"../reference/api/org/eclipse/jdt/core/IPackageFragmentRoot.html"><b>IPackageFragmentRoot</b></a>,

<a href="../reference/api/org/eclipse/jdt/core/IPackageFragment.html"><b>IPackageFragment</b></a>,
and <b>IFolder</b> as input elements:</p>
<h3>Overlaying Images With Java Information</h3>
<p><a href=
"../reference/api/org/eclipse/jdt/ui/JavaElementImageDescriptor.html"><b>JavaElementImageDescriptor</b></a>
can be used to create an image based on an arbitrary base image descriptor and a set of flags
specifying which Java specific adornments (e.g. static, final, synchronized, ....) are to be
superimposed on the image.</p>
<h3>Adding Problem and Override Decorators</h3>
When a viewer is supposed to include problem annotations, the JFace <b>DecoratingLabelProvider</b>

together with the <a href=
"../reference/api/org/eclipse/jdt/ui/ProblemsLabelDecorator.html"><b>ProblemsLabelDecorator</b></a>
is used. The snippet below illustrates the use of a problem label decorator.
<pre class="color1">
    ...
    DecoratingLabelProvider decorator= new DecoratingLabelProvider(labelProvider, new ProblemsLabelDecorator());
    viewer.setLabelProvider(decorator);
    ...
</pre>
<p>In the same way the <a href=
"../reference/api/org/eclipse/jdt/ui/OverrideIndicatorLabelDecorator.html"><b>OverrideIndicatorLabelDecorator</b></a>
can be used to decorate a normal label provider to show the implement and override indicators for
methods.</p>
<h3>Updating the Presentation on Model Changes</h3>
<p>Neither the <a href=
"../reference/api/org/eclipse/jdt/ui/OverrideIndicatorLabelDecorator.html"><b>OverrideIndicatorLabelDecorator</b></a>

nor the <a href=
"../reference/api/org/eclipse/jdt/ui/ProblemsLabelDecorator.html"><b>ProblemsLabelDecorator</b></a>
listen to model changes. Hence, the viewer doesn't update its presentation if the Java or resource
marker model changes. The reason for pushing the update onto the client for these classes is that
there isn't yet a generic implementation that fulfills all performance concerns. Handling Java
model delta inspection and viewer refreshing in each label decorator or provider would lead to
multiple delta inspections and unnecessary viewer updates.</p>
<p>So what does the client need to do in order to update their viewers ?</p>
<ul>
<li><a href=
"../reference/api/org/eclipse/jdt/ui/OverrideIndicatorLabelDecorator.html"><b>OverrideIndicatorLabelDecorator</b></a>:
the client must listen to Java model changes (see <a href="jdt_api_manip.htm#javadeltas">Responding
to changes in Java elements</a>) and decide if the change(s) described by the delta invalidates the
override indicator of elements presented in the viewer. If so, the class inspecting the delta
should trigger a repaint of the corresponding Java elements using the standard JFace viewer API
(see update methods on StructuredViewer).</li>
<li><a href=
"../reference/api/org/eclipse/jdt/ui/ProblemsLabelDecorator.html"><b>ProblemsLabelDecorator</b></a>:
the client should listen to changes notified by the decorator via a <a href=
"../reference/api/org/eclipse/jdt/ui/ProblemsLabelDecorator.ProblemsLabelChangedEvent.html"><b>ProblemsLabelChangedEvent</b></a>

(see also <a href=
"../reference/api/org/eclipse/jdt/ui/ProblemsLabelDecorator.html#addListener(org.eclipse.jface.viewers.ILabelProviderListener)">
<b>ProblemsLabelDecorator.addListener</b></a> ). Since the marker model is resource based, the
listener has to map the resource notifications to its underlying data model. For an example showing
how to do this for viewers presenting Java elements see the internal classes
<code>ProblemTreeViewer.handleLabelProviderChanged.</code></li>
</ul>
<p>For the same reasons enumerated for label decorators the <a href=
"../reference/api/org/eclipse/jdt/ui/StandardJavaElementContentProvider.html"><b>StandardJavaElementContentProvider</b></a>
doesn't listen to model changes. If the viewer needs to update its presentation according to Java
model changes, then the client should add a corresponding listener to JavaCore. If the change
described by the delta invalidates the structure of the elements presented in the viewer then the
client should update the viewer using the standard JFace API (see refresh methods on
StructuredViewer, and the add and remove methods on TableViewer and AbstractTreeViewer).</p>
<h3>Sorting the Viewer</h3>
<p><a href=
"../reference/api/org/eclipse/jdt/ui/JavaElementSorter.html"><b>JavaElementSorter</b></a> can be
plugged into a JFace viewer to sort Java elements according to the Java UI sorting style.</p>

</body>
</html>
